Align guide docs with the code on main - #373
Conversation
A page-by-page audit of docs/guide against the current crates found names that no longer exist, behaviour descriptions the code contradicts, and public surface with no coverage. This commit fixes what the audit turned up. Phantom names: dispatch_with_config / dispatch_with_config_handle (fastly, cloudflare, architecture), AxumProxyClient::default(), EDGEZERO_SECRET_ prefix, wrangler secret put --binding, diff.rs entry point, dispatch_with_*_handle, crate-root imports for types that live in proxy:: / context:: / dev_server::. Behaviour: response streaming is preserved only on Cloudflare (Fastly, Spin and Axum buffer); duplicate routes panic at build rather than first-registered-wins; Axum honours the axum.toml port through the CLI and reads EDGEZERO__LOGGING__LEVEL, not edgezero.toml; Axum KV files are .edgezero/kv-<slug>-<hash>.redb; healthcheck emits status-code only when an HTTP status arrived and degrades to service-level without a token; EDGEZERO_MANIFEST and the missing-manifest fallback apply to build/deploy/serve only; Cloudflare local push selects by --binding; deploy actions use cache/restore@v6 + cache/save@v6 and no checkout; the cache key includes the workspace path and build-args hash. Coverage: Fastly custom entry points (runtime_env_config, dispatch_with_registries, RUNTIME_ENV_STORE_NAME and the two footguns); FastlyService / CloudflareService builders; store extractors (Kv, Config, Secrets, AppConfig<C>); FnMiddleware and middleware_arc; app! argument list; adapter metadata component/host/port and auth-* command overrides; EDGEZERO__LOGGING__* rows; config push --staging as the supported staging path; Spin everywhere it was missing (landing page, platform table, architecture, roadmap, overview tests and capability table, and Logging / Proxy / Context / Testing sections on its page); Axum KV and Secret Store sections; Cloudflare Secret Store and the kv/config merged-id collision; scaffold tree and generated CLI surface; KV page added to the sidebar.
The dev server derives .edgezero/kv-<slug>-<hash>.redb for every declared id (kv_store_path in dev_server.rs); the hard-coded .edgezero/kv.redb default the module doc described no longer exists.
ChristianPavilonis
left a comment
ChristianPavilonis
left a comment
There was a problem hiding this comment.
Summary
Reviewed the locked PR revision against its base. The documentation alignment is broadly correct, with five actionable documentation corrections noted inline.
| store at a time: `.with_config(binding)` (a KV binding name), | ||
| `.with_config_handle(handle)`, `.with_kv(binding)`, `.with_secrets()`, the | ||
| matching `.require_kv()` / `.require_secrets()` flags, and finally | ||
| `.dispatch(req)`. This path takes bindings verbatim and does not resolve |
There was a problem hiding this comment.
P2: Cloudflare's documented manual dispatch call does not compile
The public method requires req, env, and ctx, and it is async (crates/edgezero-adapter-cloudflare/src/request.rs:103-108). A reader following .dispatch(req) cannot build the Worker. Please document .dispatch(req, env, ctx).await, preferably in a complete entrypoint example.
| Routes are matched by specificity (static segments first, then parameters, then catch-alls). | ||
| Registering two routes that conflict for the same method (for example, two routes that both look | ||
| like `/users/{id}`) panics when the router is built with `duplicate route definition for <path>`, | ||
| so the conflict surfaces at startup rather than at request time. |
There was a problem hiding this comment.
P2: Duplicate routes are not always caught at startup
Fastly, Cloudflare, and Spin call A::build_app() from their request entrypoints, so a conflicting route panics while handling a request. An edge deployment can therefore succeed and then fail on traffic. Please say the panic occurs when the router is constructed, noting that this is Axum startup but request-time initialization on the edge adapters.
| | `EDGEZERO__ADAPTER__PORT` | bind port (axum) | `8787` | | ||
| | `EDGEZERO__LOGGING__LEVEL` | log level | adapter default | | ||
| | `EDGEZERO__LOGGING__ENDPOINT` | named log endpoint the platform logger attaches to (Fastly only); unset means no platform logger is initialised | none | | ||
| | `EDGEZERO__LOGGING__USE_FASTLY_LOGGER` | whether to initialise the Fastly logger (Fastly only); derived from `ENDPOINT` on the runtime-env path | `true` | |
There was a problem hiding this comment.
P2: These Fastly logging controls are not applied on the runtime-env path
USE_FASTLY_LOGGER does not control initialization, and ECHO_STDOUT=false is ignored. FastlyLogging::from(&EnvConfig) derives logger use solely from ENDPOINT and hard-codes echo_stdout: true (crates/edgezero-adapter-fastly/src/lib.rs:74-103). Please remove these two rows or state that they are currently ignored; document that ENDPOINT enables the logger and stdout echo is always enabled on this path.
| provider response (Spin rejects streamed bodies over 16 MiB), so the client | ||
| receives the whole body at once | ||
|
|
||
| Use streaming for its memory and composability benefits everywhere, but only rely |
There was a problem hiding this comment.
P2: Buffering adapters do not provide the claimed memory benefit
Axum collects the complete stream into an unbounded Vec, while Spin collects it and rejects responses over 16 MiB. Large streamed responses can therefore exhaust memory or fail rather than reduce memory use. Please limit the memory-benefit recommendation to adapters that preserve streaming and describe Axum/Spin streaming as an API-composability feature only.
| | Variable | Description | | ||
| | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `EDGEZERO_MANIFEST` | Path to manifest (default: `edgezero.toml`) | | ||
| | `EDGEZERO_MANIFEST` | Path to manifest (default: `edgezero.toml`). Honoured by `build`, `deploy`, and `serve`; `provision` and the `config` subcommands take `--manifest` instead. | |
There was a problem hiding this comment.
P2: EDGEZERO_MANIFEST also applies to auth
run_auth calls load_manifest_optional() and uses manifest-defined auth-* command overrides (crates/edgezero-cli/src/auth.rs:30-32). This environment variable is also the only non-default manifest selector for auth, since that command has no --manifest flag. Please add auth to the documented scope and update the missing-manifest fallback description.
2 participants
Summary
docs/guideagainst the current crates found names that no longer exist, behaviour the code contradicts, and public surface with no coverage. This PR fixes what the audit turned up, so a reader following the guides lands on APIs and commands that exist and behave as described.Changes
docs/guide/adapters/fastly.mddispatch_with_config*with theFastlyServicebuilder; add Custom entry points (runtime_env_config,dispatch_with_registries,RUNTIME_ENV_STORE_NAME, both footguns); buffering,-C,manifest_version = 3,[setup],proxy::importdocs/guide/adapters/cloudflare.mdCloudflareServicebuilder;worker-buildbuild command;context::/proxy::imports;wrangler kv key put; Secret Store section; kv/config merged-id collisiondocs/guide/adapters/axum.mddev_server::run_app,AxumProxyClient::try_new(), bind-address precedence,EDGEZERO__LOGGING__LEVEL,owns_logging; KV Storage and Secret Store sections; KV no longer listed as unavailabledocs/guide/adapters/spin.mdrequired = truevsdefault = ""docs/guide/adapters/overview.mddocs/guide/streaming.md,proxying.mdSpinProxyClient,AxumProxyClient::try_new()?docs/guide/routing.md,handlers.md,middleware.md,kv.mdKv,Config,Secrets,AppConfig<C>);FnMiddleware/middleware_arc; Axum KV file namingdocs/guide/configuration.mdapp!argument table; adapter metadatacomponent/host/port;auth-*command overrides;rename_allandstore_refrules; compiling secret-resolution exampledocs/guide/blob-app-config-migration.mdconfig push --stagingas the supported staging path; Axum env-var andwrangler secret putforms; canary key in examples;config.rsdiff entry pointdocs/guide/manifest-store-migration.mdEDGEZERO__LOGGING__*rows; dropdispatch_with_*_handledocs/guide/cli-reference.md,cli-walkthrough.md-C/--manifest-pathserve and deploy forms; healthcheck outputs and token behaviour; Cloudflare--binding --local;pushed-key/pushed-store;EDGEZERO_MANIFESTscope;my-app.tomlin the tree; lifecycle commands in the generated CLIdocs/guide/deploy-github-actions.md,docs/specs/edgezero-deploy-github-action.mdcache/restore@v6+cache/save@v6, nocheckout; cache-key components; artifact retention and job summarydocs/guide/architecture.md,what-is-edgezero.md,roadmap.md,docs/index.mddispatch_with_configdropped from the diagramdocs/.vitepress/config.mtscrates/edgezero-adapter-axum/src/key_value_store.rs.edgezero/kv-<slug>-<hash>.redb, not the removed.edgezero/kv.redbdefaultCloses
Closes #372
Closes #361
Closes #77
Test plan
cargo fmt --all -- --checkcd docs && npm run lint && npm run format && npm run builddocs/guidereports only placeholder app names and third-party namescargo test --workspace --all-targets(no Rust code changed; one//!comment)cargo clippy --workspace --all-targets --all-features -- -D warnings(not applicable)cargo check --workspace --all-targets --features "fastly cloudflare spin"(not applicable)examples/app-demoworkspace (not applicable)edgezero serve --adapter axum(not applicable)Checklist
{id}syntax (not:id)edgezero_core(nothttpcrate)KvRegistry/ConfigRegistry/SecretRegistry(not the legacy single-handle setters) — see spec §6.6